This file explains how to use the buildAudivolv.xml file with Eclipse 3.3.2
(which is free to download at http://www.eclipse.org)
but other versions or other debuggers should work too. Try NetBeans.
Some of the variables in buildAudivolv.xml are written here. Example: ${audivolv.requiresJavaVersion}

After you do this, every time you click Save in Eclipse, a new Audivolv Jar is created,
and you can run Audivolv in Debug mode or double-click that Jar to run normally.

Audivolv should work on all operating systems.


===========
==SUMMARY==

Use UTF-8 encoding for all text (this will be automatically verified in later versions of Audivolv).
Java version is the ${audivolv.requiresJavaVersion} var below. 
Create a "jar" source-dir in an empty "Java Project" in Eclipse.
Right-click "jar", click Properties, check "Archive", and uncheck "Derived" and "Read Only".
Unzip Audivolv*.jar into that "jar" source-dir.
(The custom ClassLoader needs source-code and classes in the root dir in the Audivolv Jar.)
Replace the "Java Builder" with "Ant Builder" that uses dirty-jar and clean-jar targets.
In Builders/Refresh, choose "Refresh resources upon completion".
Clean the project once.
Debugging works because the custom ClassLoader doesnt load audivolv or javassist dirs.
If you want to debug other Jar files Audivolv loads at runtime, put them on the Eclipse classpath.

The Ant builder, "Build Options" tab, check "Specify working set of relevant resources", click "Specify Resources" and choose the whole project.


===========
==LICENSE==

If you create software including any part of Audivolv, it must be open-source
under the same GNU GPL 2+ license(s)
as explained in the LicenseOpenSource.txt file in this Audivolv Jar.


=============================================================
==YOU CAN IGNORE THE JAR FILES INSIDE THE AUDIVOLV JAR FILE== 

Jar files in ${audivolv.anyfilesDir} may be loaded while Audivolv runs and should
only be on the classpath if you want to use them in a debugger (Eclipse, NetBeans, etc).

If those Jar files are needed but not found, a window asks the user
something like "What Jar file contains the codesimian.CompilerApplet class?",
and if the user finds "CodeSimian0.65.jar", Audivolv automatically uses CodeSimian.
Common plugins, like CodeSimian, and any other files Audivolv may want,
can be included in the ${audivolv.anyfilesDir} dir, to avoid searching for them.


===========
==DETAILS==

=SET UP JAVA IN ECLIPSE=
Click Eclipse's "Window" menu, then "Preferences", then open "Java", then "Installed JREs".
You need a version of "JDK" that is
at least the version audivolv.requiresJavaVersion written below in this buildAudivolv.xml file.
If one of those is not checked, do an internet search for "download JDK" and install it,
then come back to the "Installed JREs" tab, click "Add",
click "Browse" beside "JRE home directory", and choose the dir where you installed JDK.
That dir must contain a "bin" dir with a "javac.exe" file (if operating system is Windows).
Click the "+" to the left of "Installed JREs" and click "Execution Environments".
Click "J2SE-1.5" and check the JDK you just added. Now Eclipse can use Java.
If audivolv.requiresJavaVersion in this buildAudivolv.xml file is not 1.5, use whatever version it is.

=USE THE GLOBAL LANGUAGE STANDARD=
Click Window, Preferences, General, Workspace,
and set "Text file encoding" to "Other" and type UTF-8 in it, then click OK.
UTF-8 is text that has all letters/symbols from all Ëãr†h (Earth) languages,
and when you see that Ëãr†h is similar to Earth in this file, you are in UTF-8 mode.
If you skip this language stuff, your new version of Audivolv will lose some of its text.
Optionally, read more at http://en.wikipedia.org/wiki/UTF-8

=SET UP THE AUDIVOLV PROJECT IN ECLIPSE=
Verify the "Package Explorer" subwindow is open. If its not,
then click the button in the bottom-left corner of Eclipse and find it.
In "Package Explorer", right-click, select "New", then "Other".
Create an empty "Java Project".
Choose "J2SE-1.5" beside "Use an execution environment JRE".
Create a "jar" dir in that project.
Right-click "jar", click Properties, check "Archive", and uncheck "Derived" and "Read Only".
Unzip the Audivolv Jar into that "jar" dir.
Go to "Properties" of that project.
Click "Java Build Path".
Add that "jar" dir as a "Source folder", "include" all, and do not "exclude" anything.
Click "Builders".
Uncheck "Java Builder" and ignore the warning.
Click "New" and select "Ant Builder". It starts in the "Main" tab.
Click "Browse Workspace" for "Buildfile" and choose this buildAudivolv.xml file in the "jar" dir.
Click "Browse Workspace" for "Base Directory" and choose the "jar" dir.
Click the "Refresh" tab.
Check "Refresh resources upon completion".
Click "The project containing the selected resource".
Click the "Targets" tab. There are 4 things to choose. For each, click "Set Targets".
(1) After a "Clean": Choose no targets.
(2) Manual Build: Choose only the dirty-jar target.
(3) Auto Build: Choose only the dirty-jar target.
(4) During a "Clean": Choose only the clean-jar target.
Click OK on all windows.
Verify the Console subwindow is visible in Eclipse.
In the Eclipse Project menu, check "Build Automatically", and click "Clean" once.
Go to a file, like audivolv.ui.AudivolvWindowUi, change titlePrefix, and Save.
Verify the Console subwindow shows this buildAudivolv.xml file running and "BUILD SUCCESSFUL".
You should see an Audivolv Jar file in the "jar" dir in the "Package Explorer" subwindow.
Double-click that Jar and verify the Audivolv window opens with your new window title.
Close it and Click the right part of Eclipse's bug button, and create a new startup option.
Double-click "Java Application".
Choose this "Java Project" that you just created.
Set the "Main Class" (can click Search to do this) to audivolv.Audivolv
Click Debug, and the Audivolv window opens in debug mode,
allowing you to use the Debug, Breakpoints, and Variables subwindows, etc.
You are now in the most advanced programming mode that exists on Earth.
